9. Quake-C Network Protocol

Quake-C is not supposed to handle a lot of network messages, since most are already handled by specialied functions, in the C code. However, Built-in functions have not been built for every kind of messages in the Quake protocol, so you migth end-up composing protocol messages in Quake-C. I highly recommend that you build a single function to handle a given message type, because the structure of those messages might change, and then all your code would have to be checked for bugs.

Note that with Quake-C you can only create Server to client messages (documented in the DEM specs). You cannot create client to server messages, since Quake-C is run by the server only, not the clients.

Definitions for protocol messages

How messages are sent

MSG_BROADCAST = 0;  // unreliable message, sent to all
MSG_ONE = 1;       // reliable message, sent to msg_entity
MSG_ALL = 2;       // reliable message, sent to all
MSG_INIT = 3;	// write to the init string

Use unreliable (but fast) messages, when it's of no importance that a client misses the message.
examples: sound, explosions, monster deaths, taunts....
Use reliable messages when it's very important that every client sees the message, or a game incoherency might happen.
examples: shots, player deaths, door moves, game ends ... and CD track changes!.

Type of message

These are some of message types defined in the Quake network protocol.

SVC_SETVIEWPORT = 5;
SVC_SETANGLES = 10;
SVC_TEMPENTITY = 23;
SVC_KILLEDMONSTER = 27;
SVC_FOUNDSECRET = 28;
SVC_INTERMISSION = 30;
SVC_FINALE = 31;
SVC_CDTRACK = 32;
SVC_SELLSCREEN = 33;
SVC_UPDATE = 128;

Built-in Network functions

Beware: when generating messages, you had better respect the format of the existing messages. Otherwise the game clients might not be able to interpret them (and will likely crash).

The functions below all write to clients (players connected via the network, or the local player).

Global variable for network messages

Variable: msg_entity

entity	msg_entity;

If you want to send a message to just one entity e, then set msg_entity= e and send the message with flag MSG_ONE, instead of MSG_ALL.
Never used. Maybe it doesn't even work.

Builtin functions for composing network messages

Function: WriteByte

void WriteByte(float to, float value)
       to = see messages

Function: WriteChar

void WriteChar(float to, float value)
       to = see messages

Function: WriteShort

void WriteShort(float to, float value)
       to = see messages

Function: WriteLong

void WriteLong(float to, float value)
       to = see messages

Function: WriteCoord

void WriteCoord(float to, float value)
       to = see messages

Function: WriteAngle

void WriteAngle(float to, float value)
       to = see messages

This function writes a single byte, that represents 256*(angle/380).

Function: WriteString

void WriteString(float to, string value)
       to = see messages

This function writes a string, terminated by \0 (the null character in C).

Function: WriteEntity

void WriteEntity(float to, entity value)
       to = see messages

This function writes an entity reference, taking two bytes.

9.3 Some message structures

Here are some of the messages defined in the Quake network protocol.

Beware, the structure of those messages might change in future version (Satan forbids!).

Message: Set View Position

  msg_entity = player
  WriteByte (MSG_ONE, SVC_SETVIEWPORT);
  WriteEntity( MSG_ONE, camera);

This message is meant for a single client player. It sets the view position to the position of the entity camera.

Message: Set View Angles

  msg_entity = player
  WriteByte (MSG_ONE, SVC_SETVIEWANGLES);
  WriteAngle( MSG_ONE, camera.angles_x); 
  WriteAngle( MSG_ONE, camera.angles_y);
  WriteAngle( MSG_ONE, camera.angles_z);

This message is meant for a single client player. It set the orientation of it's view to the same orientation than the entity camera.

Message: Temporary Entity

  WriteByte (MSG_BROADCAST, SVC_TEMPENTITY);
  WriteByte (MSG_BROADCAST, entityname);
  WriteCoord (MSG_BROADCAST, origin_x);
  WriteCoord (MSG_BROADCAST, origin_y);
  WriteCoord (MSG_BROADCAST, origin_z);

Message: Set CD Track

  WriteByte (MSG_ALL, SVC_CDTRACK);
  WriteByte (MSG_ALL, val1);        // CD start track
  WriteByte (MSG_ALL, val2);        // CD end track

Message: Final Message

  WriteByte (MSG_ALL, SVC_FINALE);
  WriteString (MSG_ALL, "any text you like\n");

Message: Sell Screen

WriteByte (MSG_ALL, SVC_SELLSCREEN);

Shows the infamous sell screen (like you needed it to understand).

Message: Inter Mission

WriteByte (MSG_ALL, SVC_INTERMISSION);

Shows the inter mission camera view.

Message: Killed Monster

WriteByte (MSG_ALL, SVC_KILLEDMONSTER);

Increase by one the count of killed monsters, as available to the client. Can be displayed with showscores.

Message: Found Secrets

WriteByte (MSG_ALL, SVC_FOUNDSECRET);

Increase by one the count of secrets founds.

Message: Update Entity

This message has a rather complex structure. I already generated some valid update messages, but since the message structure seems highly susceptible to change in the next versions of Quake, I would recommend that you never use such messages: as a matter of fact, Quake itslef is very capable of generating all the required messages... unless you start creating deathmatch cameras or the like.